Oauth2.0 API
Fanbook Developer
正式:https://a1.fanbook.cn/open/
#
Oauth2.0#
使用票证的授权方式#
Oauth 序列图02应用
#
获取应用信息请求格式:
• Method:GET
• Path:/open/oauth2/app
Header 参数
参数名 | 描述 |
---|---|
authorization | Fanbook 会话 token |
Query 参数
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
client_id | string | 是 | |
redirect_url | string | 否 | 授权后跳转的地址 |
返回数据:
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
app | Application | 是 | 应用信息 |
user | User | 是 | 授权用户信息 |
#
打开授权页面(**For Web**)请求格式:
• Method:GET
• Path:/open/oauth2/authorize
Header 参数
参数名 | 描述 |
---|---|
Query 参数
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
response_type | string | 是 | 固定值:code |
client_id | string | 是 | |
state | string | 否 | 自定义状态数据,传入的值会直接返回 |
返回数据:
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
#
确认授权请求格式:
• Method:POST
• Path:/open/oauth2/authorize
Header 参数
参数名 | 描述 |
---|---|
authorization | Fanbook 会话 token |
Query 参数
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
response_type | string | 是 | 固定值:code |
client_id | string | 是 | |
allow | bool | 是 | 授权行为,true: 允许,false: 拒绝 |
status_code | string | 否 | 自定义 response status code,默认返回 302,可选值:[200, 302] |
state | string | 否 | 自定义状态数据,传入的值会直接返回,一般用于安全验证,前端可以验证服务器的返回是否一致,可以是用户session的hash值,或者是可以唯一标识会话的任意值。 |
返回数据:
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
location | string | 是 | 重定向地址 |
#
换发 Token请求格式:
• Method:POST
• Path:/open/oauth2/token
Header 参数
参数名 | 描述 |
---|---|
content-type | application/x-www-form-urlencoded |
authorization | Basic {base64_encode(client_id:client_secret)} |
注意这里的content-type。另外authorization的生成,如果client_id为"123456",client_secret为"aSecret",那么authorization应为 "Basic MTIzNDU2OmFTZWNyZXQ="
Body 参数
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
grant_type | string | 是 | 固定值:authorization_code |
code | string | 是 | 通过授权获得到 code,一次使用有效 |
redirect_uri | string | 是 | 创建应用时预先设置的跳转地址 |
返回数据:
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
access_token | string | 是 | |
refresh_token | string | 是 | |
token_type | string | 是 | 固定值:bearer |
expires_in | int | 是 | |
scope | Token 适用的 scope |
#
刷新 Token请求格式:
• Method:POST
• Path:/open/oauth2/refresh
Header 参数
参数名 | 描述 |
---|---|
content-type | application/x-www-form-urlencoded |
authorization | Basic {base64_encode(client_id:client_secret)} |
Body 参数
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
grant_type | string | 是 | 固定值:refresh_token |
refresh_token | string | 是 | |
redirect_uri | string | 是 | - |
返回数据:
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
access_token | string | 是 | |
refresh_token | string | 是 | |
token_type | string | 是 | 固定值:bearer |
expires_in | int | 是 | |
scope | Token 适用的 scope |
#
使用implicit的授权方式#
时序图
#
接口说明#
打开授权页面(**For Web**)请求格式:
• Method:GET
• Path:/open/oauth2/authorize
Header 参数
参数名 | 描述 |
---|---|
Query 参数
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
response_type | string | 是 | 固定值:token |
client_id | string | 是 | |
state | string | 否 | 自定义状态数据,传入的值会直接返回 |
redirect_uri | string | 是 | 重定向地址,一定要跟申请应用时填写的重定向地址一致,否则会返回错误信息,授权失败 |
scope | string | 是 | 授权权限的枚举,多个权限值直接必须使用“%20” 连接,比如user.link%20user.info,下文有对权限的描述 |
status_code | string | 否 | 指定返回时使用的状态码,默认是返回302,可以指定为200,则会返回的body里带上location,即重定向后的地址 |
返回数据:
默认会在返回的header里包含了location字段,字段内容示例如下: http://localhost/#access_token=z7Aj7v/qN7T//uQq1ohquw==&token_type=Bearer&expires_in=3599&scope=user.link%20user.info&state=3
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
access_token | string | 是 | 返回的token信息 |
token_type | string | 是 | token的类型,目前为固定值"Bearer" |
expires_in | string | 是 | 有效时间,默认为3600秒 |
scope | string | 是 | 授权权限的枚举,多个权限值直接必须使用“%20” 连接,比如user.link%20user.info |
state | string | 否 | 自定义状态数据,返回请求里填充的state值 |
#
获取用户个人数据请求格式:
• Method:POST
• Path:/open/api/user/getMe
Header 参数
参数名 | 描述 |
---|---|
content-type | application/json |
authorization | Bearer {access_token} |
JSON 参数
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
返回数据:
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
status | bool | 是 | |
data | User | 否 | |
message | string | 否 |
#
获取个人服务器列表请求格式:
• Method:POST
• Path:/open/api/guild/getGuilds
Header 参数
参数名 | 描述 |
---|---|
content-type | application/json |
authorization | Bearer {access_token} |
JSON 参数
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
返回数据:
参数名 | 类型 | 是否必须 | 描述 |
---|---|---|---|
status | bool | 是 | |
data | Array of Guild | 否 | |
message | string | 否 |
#
Open API Types#
User用户个人信息
字段 | 类型 | 是否必须 | 描述 |
---|---|---|---|
user_id | string | 是 | 用户全局唯一 ID |
nickname | string | 是 | 用户昵称 |
username | string | 是 | 用户可读标识 ID |
avatar | string | 是 | 头像 |
token | string | 否 |
#
Application应用信息
字段 | 类型 | 是否必须 | 描述 |
---|---|---|---|
client_id | string | 是 | 应用 ID |
description | string | 是 | 应用简介 |
icon | string | 是 | 应用 ICON 标识地址 |
name | string | 是 | 应用名称 |
scopes | string | 是 | 应用申请的权限范围 |
#
GuildCredit用户服务器荣誉数据
字段 | 类型 | 是否必须 | 描述 |
---|---|---|---|
authority | CreditAuthority | 否 | 荣誉颁发者 |
title | CreditTitle | 否 | 荣誉 title,展示在聊天会话中的个人头像右侧 |
slots | Array of CreditSlot array | 是 | 荣誉槽,展示在个人信息页,是二维数组 |
#
CreditAuthority服务器荣誉颁发者详情
字段 | 类型 | 是否必须 | 描述 |
---|---|---|---|
icon | string | 是 | 荣誉颁发者形象 logo url 地址 |
name | string | 是 | 荣誉颁发者名称 |
#
CreditTitle服务器荣誉 Title
字段 | 类型 | 是否必须 | 描述 |
---|---|---|---|
img | string | 否 | 荣誉 Title 图形 url 地址 |
#
CreditSlot服务器荣誉槽
字段 | 类型 | 是否必须 | 描述 |
---|---|---|---|
label | string | 是,与 img 二选一 | 荣誉文本标题 |
img | string | 是,与 label 二选一 | 荣誉图形标题 |
value | string | 是 | 荣誉值本值 |
#
Open API 签名方法#
权限定义权限 | 描述 |
---|---|
user.info | 用户的基本信息,用户nickname和avatar等等 |
user.link | 用户的电话号码 |